Functions 🥳

Thursday, February 23nd

Today we will…

Mini lecture on text material
- Function Basics
- Environments & Scope
- Lab 7 Preview
Work time:
- PA 7: Functions
- Lab 7: Functions & Fish
- Challenge 7: Incorporating Multiple Inputs

Why write functions?

Functions allow you to automate common tasks
We’ve been using functions since Day 1
Did you ever find yourself copy-pasting an analysis and changing small parts?

Writing your OWN functions has 3 big advantages over copy-and-paste:

Your code is easier to read
To change your analysis, simply change the function
No more mistakes from copy-paste

Function Basics

Function Syntax

A (very) simple function

add_two <- function(x) {
  
  x + 2
  
}

Let’s call the function!

add_two(5)

[1] 7

Naming functions – `add_two <-`

The name of the function is chosen by the author.

add_two <- function(x) {
  
  x + 2
  
}

A word of caution: Function names have no inherent meaning.

add_three <- function(x) {
  
  x + 7
  
}

What did you expect?

add_three(5)

[1] 12

Function Arguments

The argument(s) of the function are chosen by the author.

(x)
Optional arguments
Required arguments

add_two <- function(x) {
  
  x + 2
  
}

arguments are temporary variables with general names
x, y, z – vectors
df – dataframe
i, j – indices

We can supply a default argument value – something

add_something <- function(x, something = 2) {
  
  x + something
  
}

something defaults to 2

add_something(x = 5)

[1] 7

add_something(x = 5, 
              something = 6)

[1] 11

If you do not supply a default value, the argument is required:

add_something <- function(x, something) {
  
  x + something
  
}

add_something(x = 2)

Error in add_something(x = 2): argument "something" is missing, with no default

Function `{ body }`

The body of the function is where the action happens.

add_two <- function(x) {
  
  x + 2
  
}

`return()`

Your function will “give back” whatever would normally “print out”.

add_two <- function(x) {
  
  x + 2
  
}

7 + 2

[1] 9

add_two(7)

[1] 9

Explicit `return()`s

I prefer to have explicit returns in my functions!

add_two <- function(x) {
  
  return(x + 2)
  
}

Why? It makes debugging easier.

add_two <- function(x) {
  
  sum <- x + 2
  
}

add_two(2)

add_something <- function(x, something) {
  
  stopifnot(is.numeric(x))
  
  return(x + something)
  
}

add_something(x = "statistics", something = 5)

Error in add_something(x = "statistics", something = 5): is.numeric(x) is not TRUE

add_something <- function(x, something) {
  
  if(is.numeric(x) != TRUE){
    stop("Please provide a numeric input for the x argument.")
  }
  
  return(x + something)
  
}

add_something(x = "statistics", something = 5)

Error in add_something(x = "statistics", something = 5): Please provide a numeric input for the x argument.

Recall DeMorgan’s law!

add_something <- function(x, something) {
  
  stopifnot(is.numeric(x), is.numeric(something))
  
  return(x + something)
  
}

add_something(x = 2, 
              something = "R")

Error in add_something(x = 2, something = "R"): is.numeric(something) is not TRUE

add_something(x = 2, 
              something = 4)

[1] 6

Environments

The top right pane of your RStudio shows your environment.
This is the “current state” of the objects you’ve created.

The code inside the function executes in the function environment.
It does not change your global environment.

Dynamic Lookup

If an object doesn’t exist in the function’s environment, the global environment will be searched next; if there is no object in the global environment, the program will error out.

add_two <- function() {
  
  x + 2
  
}

add_two()

Error in add_two(): object 'x' not found

x <- 10

add_two()

[1] 12

Name Masking

Objects you make in the function don’t affect “real life”.

add_two <- function(x) {
  
  my_result <- x + 2
  
  return(my_result)
  
}

my_result <- 2000

This is an example of name masking, where names defined inside of a function mask names defined outside of a function.

add_two(5)

[1] 7

my_result

[1] 2000

Debugging

Debugging Strategies

Interactive coding (highlight small lines within your function to run them independent of the rest)
print() Debugging
Rubber Ducking

In general…

Write a simple example once (without a function)
Generalize by assigning variables.
Write into a function.
Call the function on desired arguments

Example – `find_car_make()`

Write a function called find_car_make() that takes as input the name of a car, and returns only the “make”, or the company that created the car. For example, find_car_make("Toyota Camry") should return “Toyota” and find_car_make("Ford Anglica") should return “Ford”.

Example
Generalize
Write + Call Function

make <- str_extract(string = "Toyota Camry", 
            pattern = "[:alpha:]*"
            )
make

[1] "Toyota"

car_name <- "Toyota Camry"

make <- str_extract(string = car_name, 
                    pattern = "[:alpha:]*"
                    )
make

[1] "Toyota"

find_car_make <- function(car_name){
  
  make <- str_extract(string = car_name, 
                      pattern = "[:alpha:]*"
                      )
  return(make)
  
}

find_car_make("Toyota Camry")

[1] "Toyota"

Calling functions in data sets

Consider mtcars

data(mtcars)
head(mtcars, n = 3)

               mpg cyl disp  hp drat    wt  qsec vs am gear carb
Mazda RX4     21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
Mazda RX4 Wag 21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
Datsun 710    22.8   4  108  93 3.85 2.320 18.61  1  1    4    1

Let’s use our function to create a new column in the data called make that gives the make of each car!

`rownames_to_column()` ❤️

mtcars |> 
  rownames_to_column("make_model") |> 
  mutate(make = find_car_make(make_model),
         .after = make_model
         ) |> 
  head(n = 3)

     make_model   make  mpg cyl disp  hp drat    wt  qsec vs am gear carb
1     Mazda RX4  Mazda 21.0   6  160 110 3.90 2.620 16.46  0  1    4    4
2 Mazda RX4 Wag  Mazda 21.0   6  160 110 3.90 2.875 17.02  0  1    4    4
3    Datsun 710 Datsun 22.8   4  108  93 3.85 2.320 18.61  1  1    4    1

Lab 7 & Challenge 7

Lab 7: Functions & Fish

Challenge 7: Incorporating Multiple Inputs

Standardizing Between 0 and 1

std_to_01 <- function(var) {
  stopifnot(is.numeric(var))
  
  num <- var - min(var, na.rm = TRUE)
  denom <- max(var, na.rm = TRUE) - min(var, na.rm = TRUE)
  
  num / denom
}

Could our function be more efficient?

Ugh. Still copy + pasting!

penguins |> 
  mutate(bill_length_mm    = std_to_01(bill_length_mm), 
         bill_depth_mm     = std_to_01(bill_depth_mm), 
         flipper_length_mm = std_to_01(flipper_length_mm), 
         body_mass_g       = std_to_01(body_mass_g)
  )

Recall across()!

penguins |> 
  mutate(across(.cols = bill_length_mm:body_mass_g,
                ~ std_to_01(.x)
                )
  )

New option: Variables as Arguments!

std_column_01 <- function(data, variable) {
  
  stopifnot(is.data.frame(data), 
            is.numeric(variable)
            )
  
  data <- data |> 
    mutate(variable = std_to_01(variable))
  
  data
  
}

Note

Notice how I relied on the existing function std_to_01() inside the new function, for clarity!

But it didn’t work…

std_column_01(penguins, body_mass_g)

Error in std_column_01(penguins, body_mass_g): could not find function "std_column_01"

Tidy evaluation

Functions that use unquoted variable names as arguments are called nonstandard evaluation or tidy evaluation.

Tidy:

penguins |> 
  pull(body_mass_g)

penguins$body_mass_g

Untidy:

penguins[, "body_mass_g"]

penguins[["body_mass_g"]]

Solution 1 🤷

Just don’t use tidy evaluations in your functions
Harder to read / use, but safe

std_column_01 <- function(data, variable) {
  
  stopifnot(is.data.frame(data), 
            is.character(variable))
  
  data[[variable]] <- std_to_01(data[[variable]])
  
  data
}

std_column_01(penguins, "bill_length_mm")

Solution 2 – Embrace Injection `library(rlang)`

In February 2020 rlang introduced the “injection” {{ }} operator to simplify writing functions around tidyverse pipelines.

With the {{ }} operator you can inject the name of data-variables (i.e. columns from the data frames) into function arguments!

Warning

This only works for select() type functions, that use a literal (tidy) name of the variable to subset the data.

Recall Our Broken Function

std_column_01 <- function(data, variable) {
  
  data <- data |> 
    mutate(
      variable = std_to_01(variable)
    )
  
  data
  
}

std_column_01(penguins, body_mass_g)

Error in `mutate()`:
ℹ In argument: `variable = std_to_01(variable)`.
Caused by error in `stopifnot()`:
! object 'body_mass_g' not found

The problem here is that mutate() defuses the R code it was supplied.
Instead we want it to see body_mass_g = standardize(body_mass_g).

This is why we need injection!

std_column_01 <- function(data, variable) {
  
  stopifnot(is.data.frame(data))
  
  data <- data 
    mutate({{ variable }} = std_to_01( {{ variable }})
           )
  data
}

Error: <text>:6:27: unexpected '='
5:   data <- data 
6:     mutate({{ variable }} =
                             ^

Danger

Oh no! What happened?

The left hand side of = is also diffused!

The “Walrus Operator” `:=`

The “walrus operator” := is an alias of = that forces operations on the left hand side to not be diffused.
You can use it to supply names, e.g. a := b is equivalent to a = b.
While you could use this in an “ordinary” mutate() it is not necessary!

std_column_01 <- function(data, variable) {
  
  stopifnot(is.data.frame(data))
  
  data <- data |>
    mutate({{ variable }} := std_to_01( {{ variable }})
           )
  data
  
}

Don’t forget about `across()`

What if I want to modify multiple columns?

std_column_01 <- function(data, variables) {
  
  stopifnot(is.data.frame(data))
  
  data <- data |> 
    mutate(across(.cols = {{ variables }}, 
                  ~ std_to_01(.x)
                  )
           )
  
  data
  
}

std_column_01(penguins, bill_length_mm:body_mass_g)

Missing Data are important!

Assumptions when removing missing data

Without inspection:

Observations are “missing completely at random”

With information about the “missingness”:

Observations are “missing at random”

Look for patterns!

Missing data – Example

If fish length measurements are missing at random, conditional on month, year, and river section,

then the distributions of lengths will be similar for fish of the same month, year, and river section.

Scaling Variables

Why Scale?

Easier to compare across variables
Easier to model (standardizes variance)

Why not Scale?

Difficult to interpret

Interesting reads

Article on How Building Functions with Variable Names has Changed Over the Years

rlang Article on Data Masking

Functions 🥳

Thursday, February 23nd

Why write functions?

Function Basics

Function Syntax

A (very) simple function

Naming functions – add_two <-

Function Arguments

Function { body }

return()

Explicit return()s

Input validation

Environments

Environments

Dynamic Lookup

Name Masking

Debugging

Debugging Strategies

Example – find_car_make()

Calling functions in data sets

rownames_to_column() ❤️

Lab 7 & Challenge 7

Standardizing Between 0 and 1

Ugh. Still copy + pasting!

New option: Variables as Arguments!

Tidy evaluation

Solution 1 🤷

Solution 2 – Embrace Injection library(rlang)

Recall Our Broken Function

{{ variable }}

The “Walrus Operator” :=

Don’t forget about across()

Missing Data are important!

Assumptions when removing missing data

Missing data – Example

Scaling Variables

Interesting reads

Naming functions – `add_two <-`

Function `{ body }`

`return()`

Explicit `return()`s

Example – `find_car_make()`

`rownames_to_column()` ❤️

Solution 2 – Embrace Injection `library(rlang)`

The “Walrus Operator” `:=`

Don’t forget about `across()`